Expose isFinished() on AgentSpan by pavlokhrebto · Pull Request #11884 · DataDog/dd-trace-java

pavlokhrebto · 2026-07-08T11:56:50Z

What Does This Do

Adds a non-breaking default boolean isFinished() to the AgentSpan interface (internal-api), surfacing the finished state that DDSpan already tracks (durationNano != 0) so other modules can query it without reaching into dd-trace-core.

DDSpan's existing isFinished() overrides the default — no behavior change.
The TrackingSpanDecorator test wrapper (the only AgentSpan wrapper) delegates to its wrapped span.
Leaf / synthetic spans (NoopSpan, etc.) keep the false default.
Adds a DDSpanTest case asserting false before finish / true after, exercised through the AgentSpan interface.

Motivation

The FFE span-enrichment interceptor (#11658) needs to tell a truly-finished local-root span from a still-running one — with long-running traces enabled, a periodic flush emits the still-running root, and the interceptor currently mis-reads "root present in the flushed batch" as "trace finished". It also wants to resolve the root in O(1) instead of scanning the batch. Both need a finished signal on the interface it uses (AgentSpan). DDSpan already has it, but the interface didn't expose it; this closes only that gap. The consumer change (the interceptor rewrite) lands as a separate follow-up on #11658.

Additional Notes

Non-breaking: it's a default method, so no existing AgentSpan implementer has to change. Making it abstract would break every implementer.
No behavior change to existing spans — DDSpan already returns this value.
Deliberately does not touch MutableSpan / dd-trace-api (the FFE interceptor casts to AgentSpan).

Contributor Checklist

Format the title according to the contribution guidelines
Assign the type: and (comp: or inst:) labels in addition to any other useful labels
Avoid using close, fix, or any linking keywords when referencing an issue
Use solves instead, and assign the PR milestone to the issue
Update the CODEOWNERS file on source file addition, migration, or deletion
Update public documentation with any new configuration flags or behaviors
Add your completed PR to the merge queue by commenting /merge. You can also:
- Customize the commit message associated with the merge with /merge --commit-message "..."
- Remove your PR from the merge queue with /merge -c
- Skip all merge queue checks with /merge -f --reason "reason"; please use this judiciously, as some checks do not run at the PR-level (note: the PR still needs to be mergeable, this will only skip the pre-merge build)
- Get more information in this doc

Add a non-breaking default boolean isFinished() to the AgentSpan interface (internal-api), surfacing the finished state DDSpan already tracks (durationNano != 0) so other modules can query it without reaching into dd-trace-core. DDSpan's existing method overrides the default; the TrackingSpanDecorator test wrapper delegates; leaf/synthetic spans (NoopSpan etc.) keep the false default. Adds a DDSpanTest case covering false-before / true-after-finish via the interface. Motivated by the FFE span-enrichment interceptor (PR #11658), which needs to distinguish a truly-finished local root from a still-running one (long-running traces) and resolve it in O(1); that consumer lands in a separate follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dd-octo-sts · 2026-07-08T11:57:04Z

Hi! 👋 Thanks for your pull request! 🎉

To help us review it, please make sure to:

Add at least one type, and one component or instrumentation label to the pull request

If you need help, please check our contributing guidelines.

dd-octo-sts · 2026-07-08T11:59:42Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.86 s	14.63 s	[+0.7%; +2.5%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.65 s	13.70 s	[-1.3%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	16.85 s	16.68 s	[-0.1%; +2.1%] (no difference)
startup:petclinic:iast:Agent	16.77 s	16.93 s	[-1.9%; +0.0%] (no difference)
startup:petclinic:profiling:Agent	16.53 s	16.81 s	[-2.8%; -0.5%] (maybe better)
startup:petclinic:sca:Agent	16.91 s	16.15 s	[+0.3%; +9.2%] (maybe worse)
startup:petclinic:tracing:Agent	16.04 s	15.72 s	[-2.3%; +6.4%] (no difference)

Commit: 9f5d7765 · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

Copilot

Pull request overview

Adds a non-breaking isFinished() default method to the AgentSpan interface so modules depending on internal-api can query span completion without reaching into dd-trace-core, while preserving existing behavior for DDSpan.

Changes:

Introduces default boolean isFinished() on AgentSpan (default false).
Adds a DDSpanTest case asserting isFinished() transitions from false to true after finish(), via the AgentSpan interface.
Updates TrackingSpanDecorator (test wrapper) to delegate isFinished() to the wrapped span.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentSpan.java	Adds `isFinished()` as a default method on the core span interface.
dd-trace-core/src/test/java/datadog/trace/core/DDSpanTest.java	Adds coverage to validate `AgentSpan.isFinished()` reflects `DDSpan` completion.
dd-java-agent/instrumentation-testing/src/main/groovy/datadog/trace/agent/test/TrackingSpanDecorator.groovy	Delegates `isFinished()` in the `AgentSpan` test wrapper.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

datadog-datadog-prod-us1 · 2026-07-08T12:54:36Z

🎯 Code Coverage (details)
• Patch Coverage: 0.00%
• Overall Coverage: 56.47% (-0.47%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 9f5d776 | Docs | Datadog PR Page | Give us feedback!}

AlexeyKuznetsov-DD

LGTM.
It would probably be worth getting one more approval from an experienced reviewer before merging.

…-span

sarahchen6 · 2026-07-09T17:33:03Z

+   * @return {@code true} once this span has finished (its duration is set). Implementations that do
+   *     not track finish state always return {@code false}.
+   */
+  default boolean isFinished() {


Would it make more sense to not have this default to false? i.e. just boolean isFinished();

It looks like the classes that implement AgentSpan, are TrackingSpanDecorator (addressed in PR already), DDSpan (already has isFinished() defined, so just needs an @Override), and ImmutableSpan (would need implementation). This would make behavior explicit per span implementation.

sarahchen6

LGTM, but cc @PerfectSlayer to confirm internal-api changes are okay

PerfectSlayer

Evaluating a remote span as always finished seem wrong.

But I would like to get back at the motivation first because it's unclear why it's needed in the first place:

The FFE span-enrichment interceptor (#11658) needs to tell a truly-finished local-root span from a still-running one

That tells it needs it but not why, right?

— with long-running traces enabled, a periodic flush emits the still-running root, and the interceptor currently mis-reads "root present in the flushed batch" as "trace finished".

Sure but that's the principle of the interceptor. By the way, we want to get rid of it - that mean we will introduce some other capabilities as alternatives.

It also wants to resolve the root in O(1) instead of scanning the batch.

Sure, but why?

Both need a finished signal on the interface it uses (AgentSpan).

Who's both?

DDSpan already has it, but the interface didn't expose it; this closes only that gap.

Yes, it's sort of expected to hide the implementation details. Even the OTel span API would need it implemented its own logic rather than exposing the wrapped DDSpan internals.

So, back to the original question, what's the need of getting the state of the span? Why do you need to figure out if it's finished or not? And by the way, the direction the next API would go is, if a span is finished, it will be immutable.

pavlokhrebto · 2026-07-10T08:56:42Z

Thanks @PerfectSlayer — you comment is really helpful.
The concrete "why": the FFE interceptor writes the ffe_* tags onto the local root when the trace completes. With long-running traces, PendingTrace periodically flushes the still-open root, and the interceptor currently treats "root present in the flushed batch" as "trace finished" — so it drains and writes on the first periodic snapshot and then loses every flag evaluated afterward. To write once at real completion it needs to know the root is actually finished. ("Both" = that fix + dropping the O(N) findLocalRootInFragment scan by resolving the root via getLocalRootSpan() and acting only when finished.)

That said, your points land: if the interceptor mechanism is going away with an alternative coming, adding AgentSpan API to support it is the wrong direction; exposing DDSpan's finished state does leak an impl detail; and "finished ⇒ immutable" is a cleaner model than a boolean getter.

Since #11658 is approved and doesn't depend on this (the long-running case is off-by-default and currently a documented known limitation), I'm happy to not pursue this. I'd propose parking #11884 and revisiting the FFE long-running fix when the interceptor-replacement capability lands — unless you'd prefer we use a different signal now, in which case what would you suggest?

pavlokhrebto requested review from a team as code owners July 8, 2026 11:56

pavlokhrebto requested review from mhlidd and removed request for a team July 8, 2026 11:56

dd-octo-sts Bot added the tag: ai generated Largely based on code generated by an AI or LLM label Jul 8, 2026

pavlokhrebto added comp: core Tracer core type: feature Enhancements and improvements tag: no release notes Changes to exclude from release notes labels Jul 8, 2026

pavlokhrebto requested review from AlexeyKuznetsov-DD, PerfectSlayer, Copilot and sarahchen6 July 8, 2026 12:35

Copilot started reviewing on behalf of pavlokhrebto July 8, 2026 12:36 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentSpan.java

Potential fix for pull request finding

abd6fab

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

AlexeyKuznetsov-DD reviewed Jul 8, 2026

View reviewed changes

Merge branch 'master' into pavlo.khrebto/dd-span-finished-state-agent…

9f5d776

…-span

sarahchen6 reviewed Jul 9, 2026

View reviewed changes

sarahchen6 approved these changes Jul 9, 2026

View reviewed changes

PerfectSlayer reviewed Jul 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Expose isFinished() on AgentSpan#11884

Expose isFinished() on AgentSpan#11884
pavlokhrebto wants to merge 3 commits into
masterfrom
pavlo.khrebto/dd-span-finished-state-agent-span

pavlokhrebto commented Jul 8, 2026 •

edited

Loading

Uh oh!

dd-octo-sts Bot commented Jul 8, 2026

Uh oh!

dd-octo-sts Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

datadog-datadog-prod-us1 Bot commented Jul 8, 2026 •

edited by datadog-prod-us1-4 Bot

Loading

Uh oh!

AlexeyKuznetsov-DD left a comment

Uh oh!

sarahchen6 Jul 9, 2026

Uh oh!

sarahchen6 left a comment

Uh oh!

PerfectSlayer left a comment

Uh oh!

pavlokhrebto commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

pavlokhrebto commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contributor Checklist

Uh oh!

dd-octo-sts Bot commented Jul 8, 2026

Uh oh!

dd-octo-sts Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

datadog-datadog-prod-us1 Bot commented Jul 8, 2026 • edited by datadog-prod-us1-4 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlexeyKuznetsov-DD left a comment

Choose a reason for hiding this comment

Uh oh!

sarahchen6 Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

sarahchen6 left a comment

Choose a reason for hiding this comment

Uh oh!

PerfectSlayer left a comment

Choose a reason for hiding this comment

Uh oh!

pavlokhrebto commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pavlokhrebto commented Jul 8, 2026 •

edited

Loading

dd-octo-sts Bot commented Jul 8, 2026 •

edited

Loading

datadog-datadog-prod-us1 Bot commented Jul 8, 2026 •

edited by datadog-prod-us1-4 Bot

Loading